Cattails: Wildwood Story - Community Content Documentation

Game Version: Release v1.21

Cattails: Wildwood Story is an expansive game with many features. A selection of these features can be modified to change, improve, or add to the player's overall experience. This documentation will provide all the information you need to modify your copy of Cattails: Wildwood Story.

In general, most assets and content can be modified; while code and mechanics cannot.

Please do note that Cattails: Wildwood Story can only be modified on the PC (Windows) platform at this time.

Table of Contents

• Getting Started
• Creating a Mod: Overview
• Lowercase Filenames!
• Mod Examples (Downloads)
• Restoring Your /gameresources Folder (A.K.A. Help, I messed up and now my game won't load!)
• A Note About JSON
• Important File Locations
  • Game Installation Path
  • App Data Path
• Save Files
• Coat Studio Files
• Language Files
  • Supported Characters & Languages
  • Adding & Editing Languages
  • Special Keys
  • Language Icons
• Time
• NPCs
  • Portraits
  • Icons
  • Metadata
  • Buddy System Traits
  • Scheduling
  • Ranks
  • Dialog Files
    • Question & Answer Prompts
    • Dialog Objects
    • Special Dialog Language Keys
    • Dialog Object Filters
    • Rival Marriages
• Events
  • Event Filters
  • Event Blocks
• Bundles
• Shops
  • Item Filters
• Items
  • All Default Item Unique Identifiers
  • Item Sprites
  • Accessories
    • Accessory Sprites
  • Herbs
  • Item Language Files
• Furniture
  • Furniture Meta Files
  • Furniture Language Files
  • Furniture Image Files
    • Animated Furniture Image Files
• Mail
  • Mail Meta Files
  • Mail Paper Types
  • Mail Filters
  • Mail Language Files
• Map Regions
  • Background Types
  • World Map Sprite
  • Region Templates
    • Template Image Previews
  • World Objects
    • All Default World Objects
    • World Object Metadata
    • World Object Sprites
  • Custom Sprites
  • Tile Coordinates
  • Water Tiles
    • All Water Tile Types
  • Decorative Tiles
  • Path Tiles
    • All Path Tile Types
  • Cliff Tiles
  • Stair Tiles
  • All Prey
  • Spawners
  • Region Language Files
• Music
  • Music Packs
• Colony Emblems
• Festivals
• Crafting Stations
• Recipes
• Colony Layouts
• Buildings
• Tasks
• Wedding Venues
• Power Paw Indices
• Legal

Getting Started

To begin modifying game content, you'll need at least:

1. A copy of Cattails: Wildwood Story installed on your PC;
2. A text editor;
3. An image editor.

Cattails: Wildwood Story is available on the Steam store. You'll need a free Steam account in order to purchase a license to install the game. If you're new to Steam, you'll also need to download and install the Steam client, which manages Cattails: Wildwood Story installations for you.

Recommended text editors include Atom or Notepad++, but the basic Windows program Notepad will do the trick as well. There are a large variety of image editors available, but a free program such as Gimp can provide all the required tools.

Creating a Mod: Overview

A mod pack consists of several files stored in specific folders. Generally, these will be text or image files. To create a mod, navigate to the Steam installation folder for Cattails: Wildwood Story (see below), then navigate to the /datafiles subdirectory.

From here, you'll see a very important subdirectory: gameresources. The game reads all of its data and receives much of the information about how to run the game from this folder.

IMPORTANT: NEVER EDIT THE FILES IN THE /gameresources DIRECTORY! These files should remain untouched. They are available for your reference only and should not be edited or moved in any way. Doing so could cause the game to become unstable and crash. Doing so could also lead to a loss of your modifications when Steam auto-updates the game by deleting your changes!

Instead of editing the /gameresources files directly, we'll create a new mod pack in the /mods directory. Start by creating a new folder and name it whatever you'd like your mod to be named. For example, you might make an empty folder named "tylers awesome mod" that will be placed at the location App Data Path/mods/tylers awesome mod. For example, on Windows, you might create a new mod pack folder in %LOCALAPPDATA%/Cattails_Wildwood_Story/mods/tylers awesome mod. If the /mods directory does not exist in your App Data Path, create it as a new folder first.

By creating a new folder for our mod, we are creating a clean environment where we can isolate our own changes without interfering with what other modders have done. This will allow a player to download and use multiple mods at once with a lower chance of an unfortunate merge conflict between the mods. This is another reason that you should never edit the gameresources files or folders directly.

Alright, so we have a brand new empty folder for our mod! Great. Let's call this empty folder location the root of our mod. What do we do next?

That depends on what you'd like to mod! In general, we'll be replicating the structure of the /gameresources directory in our mod folder. For example, if you want to modify an npc, let's say Coco, you'd find all of Coco's files under the /gameresources/npcs directory and copy them into your mod folder, recreating subdirectories where needed.

For an NPC specifically, that means you'd have the following structure created in your mod folder, along with several files. We'll also create a readme.txt file with details about our mod (this is just for us to put any important info about our mod into, the game will ignore all .txt files when it loads in your files.)

• npcs (folder)
  • coco.meta (text file)
  • lang (folder)
    • english (folder)
      • coco.lang (text file)
  • icons (folder)
    • cocoicon.png (image file)
  • portraits (folder)
    • coconeutral.png (image file)
    • cocoplayful.png (image file)
    • cocohappy.png (image file)
    • cocosad.png (image file)
    • cocoangry.png (image file)
    • cocothinking.png (image file)
    • cocoblushing.png (image file)
    • cocoshocked.png (image file)
    • cocospecial.png (image file)
• readme.txt (text file)

We're only copying/creating files that we want to change into our mod folder, so don't copy or create a file here that you don't actively want to alter in some way or another. At the end of the day the fewer files you have to put in your mod folder the better because it will reduce the risk of a file collision, which the game will detect and refuse to load your mod if it conflicts with another.

Next, we'll edit the files we've decided to modify to our liking, editing them in a text editor or image manipulation program however we see fit, using this documentation as a guide for each file and what it requires.

To distribute your mod, .zip up your mod folder and upload it somewhere that it can be viewed and downloaded by others. They'll need to download your archive, unzip it, and place your mod folder in the appropriate spot (App Data Path/mods/your mod folder).

Lowercase Filenames! (Important)

All filenames and directory names must be entirely lowercase. If you do not lowercase all your filenames in your mods, you may break compatibility!

Mod Examples (Downloads)

Want to see how a mod comes together? Download our example mods here.

Instructions: Pick a mod example below to download. Unzip the .zip folder and place the entire subfolder onto your computer at %LOCALAPPDATA%/Cattails_Wildwood_Story/mods (or at the App Data Path/mods.) If the /mods folder does not exist, create it first.

For example, you might download npcmodexample.zip. You'd extract the folder and move the entire contents of the npcmodexample subfolder into %LOCALAPPDATA%/Cattails_Wildwood_Story/mods/npcmodexample.

Then, simply load up your copy of the game. If the mod was loaded successfully, you'll see a popup appear with information as soon as you get to the Main Menu. This popup will also alert you if the mod failed to load due to a file conflict with another mod you have installed.

• test npc.zip
• fast time mod.zip
• new box furniture.zip
• new emblem.zip

Restoring Your /gameresources Folder (A.K.A. Help, I messed up and now my game won't load!)

Did you mess up your /gameresources folder by modifying/adding to/deleting the files within? Don't worry! It's not the end of the world!

We'll simply have to redownload the entire /gameresources folder from Steam's servers directly. It's a fairly simple process!

First, delete the entire /gameresources folder by navigating to the Game Installation Path then right-clicking the /gameresources folder and selecting Delete.

Important: Deleting the /gameresources folder will erase any and all changes you've made to the files within! If you created a mod the wrong way (by modifying these files directly,) you probably want to save your modded files by copying them somewhere else safe before deleting them. You can likely recreate your mod the proper way with these files (see above for more info).

(You can also find the /gameresources folder by opening Steam, finding "Cattails: Wildwood Story" in your library, right-clicking "Cattails: Wildwood Story" in the lefthand pane, selecting "Manage -> Browse Local Files")

Next, we'll redownload the game resources from Steam's servers. We'll need to Verify File Integrity on Steam.

Find "Cattails: Wildwood Story" in the lefthand pane of the Library tab in Steam. Right-click "Cattails: Wildwood Story", select "Properties", then in the window that opens, go to "Local Files". Finally, select "Verify Integrity of Game Files..."

Steam will now redownload your gameresources folder and you'll have a fresh, unmodified copy.

When the verification process completes and Steam has finished downloading the files, try launching your game again!

A Note About JSON

Many of the files that store important game information and can be modified are formatted as JSON. JSON, or JavaScript Object Notation, is very useful for storing large amounts of dynamic data. It is also fairly human-readable, which should make the job of modifying Cattails: Wildwood Story a bit easier.

However, like many languages and filetypes, JSON has a strict format that must be followed in order for a file to be considered valid. If a JSON file contains invalid data for any reason, Cattails: Wildwood Story will not be able to read the data from that file and the game will likely throw errors, or even crash, depending on which file is affected. Please be sure to double-check all your JSON files to make sure that you've closed quotations and brackets, provided commas to all but the last items in a list, etc.

If you are struggling to get the format exactly right, there are a number of online JSON Validators available, which will allow you to copy and paste your JSON and see if there are any outstanding errors. This may help quite a bit, especially if you are new to the world of JSON!

Important File Locations

All Cattails: Wildwood Story-related files are found in two locations on your computer.

Game Installation Path

This is the folder where Cattails: Wildwood Story is installed on your computer. Almost all types of data files (languages, NPCs, stores, portraits) can be found here under the /gameresources directory. DO NOT EDIT THE FILES STORED IN GAMERESOURCES DIRECTLY!! See above for best practices in creating a mod for Cattails: Wildwood Story.

For Steam installations:

1. On Windows: The default location is C:/Program Files (x86)/Steam/steamapps/common/Cattails Wildwood Story
2. On Mac: The default location is ~/Library/Application Support/Steam/steamapps/common/Cattails Wildwood Story

App Data Path

This is the folder where Cattails: Wildwood Story stores user data, including save files, Coat Studio image files, and mods. Players may wish to copy their files from this location and send them along to others (such as custom coat color designs or neat save files.)

1. On Windows: The default location is %LOCALAPPDATA%/Cattails_Wildwood_Story
2. On Mac: The default location is ~/Library/Application Support/Cattails_Wildwood_Story

Save Files

There are 10 save slots available in Cattails: Wildwood Story. The save data is stored in unencrypted JSON .sav files located in the %LOCALAPPDATA%/Cattails_Wildwood_Story/saves directory.

Each slot has its own .sav file (for example, Slot 1 corresponds to the slot1.sav file.) You can open these files in any text editor and modify the values stored within, just be careful that you always maintain valid JSON formatting when you've finished editing.

In this directory you may also find a backups subdirectory. This folder contains automatic backup .sav files generated by the game during runtime. These files contain a copy of the data stored in your saveslots and will be auto-restored if anything happens to the normal .sav files. Because of this, if you are trying to delete your savefiles directly from a file explorer window, you will need to also clear out the corresponding backup files or else the game will auto-restore them to the appropriate slot when it is run.

It is not recommended that you modify, copy, delete, or otherwise tamper with the savefiles directory while the game is actively running. Doing so may cause unexpected errors to occur. Please close Cattails: Wildwood Story before attempting to alter your savefiles manually.

Backup File Types

There are two types of backup files: slot#backup.sav files and slot#backup_old.sav files. Generally, when restoring from backups, you'll want to use the normal backup.sav files as they tend to be more recent savedata. The backup_old.sav files are created the last time the game was successfully shut down, so restoring from a backup_old.sav file may result in a loss of recent progress. The auto backup restoration process always prioritizes normal backup.sav files over backup_old.sav files, but both are maintained just in case.

Corrupted Savedata

If your savedata is corrupted, the game will display an error when you attempt to load the file. The game detects corruption by locating a number of important keys from within the savedata. If it is unable to read the keys, it will label the file as corrupted. You may be able to manually restore your file by restoring a backup .sav, but your data may also be lost.

Savedata is too Old/Too New to Load

Some versions of Cattails: Wildwood Story may not be compatible with some savefiles, depending on the version the savefile was created on and the version of the game you are currently running. In particular, if the savefile was created using a newer version of Cattails: Wildwood Story, the game will refuse to load the file. Additionally, some versions of the game may reject a load attempt on a file that is deemed to be too old.

If this is the case for your savefile, you may attempt to force the game to load the file anyways by altering the "version_major", "version_minor", and "version_type" keys within your savefile to match the current version you are running. Note that doing so may lead to unintended consequences or bugs, so proceed at your own risk.

The version is displayed in the lower left hand corner of the main menu. For example, it may read "Alpha v0.5", in which case the "version_type" should be set to "Alpha", "version_major" should be set to 0.0, and "version_minor" should be set to 5.0.

A Note About Steam Cloud

When running Cattails: Wildwood Story through Steam, a feature called Steam Cloud is enabled by default. Steam Cloud attempts to keep your savefiles syncronized across all your devices logged into the same Steam account by uploading your files to a remote server everytime you exit the game and restoring the remote versions of your files everytime you start the game.

This feature may cause unexpected savedata changes if you manually alter your savefiles for any reason because Steam may overwrite your changes the next time you run the game. You can disable Steam Cloud at any time if it is causing you problems. Please refer to the official Steam Cloud documentation for more information on how to enable/disable Steam Cloud for Cattails: Wildwood Story.

Coat Studio Files

Within the App Data Path (see discussion above,) you'll find a /colors directory as long as you have at least 1 custom color design. If not, you may add an empty folder named "colors" to this location.

This folder contains PNG image files that store the data for custom coat designs. These files serve 2 primary purposes:

1. To store custom player-designed coat color designs;
2. To be used as "digital trading cards" and be swapped between friends so that others can use your color designs within their own copies of Cattails: Wildwood Story.

Below is an example of one of these files:

A player can quickly make a new coat color design through the in-game Coat Studio menu by navigating to the end of the colors list and clicking the "+ New" button. Upon completing their design, a new image file will be saved to the disk at this location.

It's important that you do not edit these files on disk while the game is running, as the game only checks for new files at very specific times while running and it may not pick up your changes.

Each image file is 256x256 pixels and is named in the following manner:

1. The string color_profile__ (note the double underscores), which notes the file as a custom color profile;
2. The custom color's display name, which will appear in-game;
3. The string __#uniqueID# (note the double underscores), where #uniqueID# MUST be a unique string of 10 lowercase alphanumeric characters (here's an online generator for your convenience);
4. Terminated by the file extension, .png.

A few examples of valid color file names:

• color_profile__Charcoal__q2tgp243rf.png
• color_profile__Raspberry Sherbert__bvsfu83jrb.png
• color_profile__Ruddy Calico__tgtgdn9adg.png

The actual image itself isn't all that important, with one crucial exception: The game uses a 1-pixel tall by 24-pixels wide strip of pixels, located in the upper-left hand corner of the image files, to store the actual color data for the design. The rest of the image may be altered, but it will have no impact on how the coat design displays in-game. You can see the strip of pixel color data fairly easily by zooming on on the upper-left hand corner. Leave it alone unless you want to change the colors of the design!!

Also, because this small strip of pixels is so important, it's extremely important that anytime you share one of these files with a friend, you must send an uncompressed copy of your file with its name intact. Any sort of file compression or renaming of the file will result in an unusable coat studio file.

Language Files

Language files contain top-level translations for most non-dialog text (and special dialog text) in the game. These files can be found in the Game Installation Path (see discussion above) in the /gameresources/languages directory.

Several of these files are provided by the developers and our localization partners so that the game can easily be played around the world, but some users may wish to use these files to add support for additional languages.

Supported Characters & Languages

Cattails: Wildwood Story uses a custom, hand-drawn font. Because of the extremely vast number of languages and characters, the game can only support certain character sets.

The following character sets are supported by the game engine and may be used in a Language or Dialog file:

• Arabic numerals (0-9)
• Standard Latin alphabet (a, b, c, ...z)
• Most special Western Latin characters (Á, Ë, Ñ, Ý, etc.)
• Standard Polish alphabet (ą, ł, ź, etc.)
• Standard Russian alphabet (а, б, в ...я)

Adding & Editing Languages

To add support for a new language, it is recommended that you copy the file english.lang (the most complete and accurate file, as it is our developer's first language), rename it according to the instructions below, and work from your new copy. It should be noted that solely translating a top-level Language File will not yield a complete translation, as NPC dialog is stored in a different directory. Please see the section on Dialog Files for more information.

A language file is named in the following manner:

1. Language Display Name;
2. Terminated by the file extension, .lang.

A few examples of valid language file names:

1. english.lang
2. deutsche.lang
3. español.lang
4. français.lang

The contents of a .lang file are structured in the JSON format. Essentially, the contents are structured as human-readable key-value pairs. Below is a sample from english.lang:

Note that on each line, there is a key (for example, "lang_summer") and a value (for example, "Summer".)

The contents of español.lang (the Spanish language file) would look a bit different (note that the game title does not get translated in this particular case):

In all cases, the key does not get translated, whereas the value usually does.

Keys will almost always begin with the substring "lang_". Below are some special cases to watch out for when translating:

• Some values contain unique placeholders (always in the format #placeholder#) that the game engine will replace with appropriate text. Please do not translate these placeholders, but you are free to move them around within the value string.
  • Example: "lang_collected": "You've collected #number_collected#." The placeholder #number_collected# will be detected by the game engine, and the true number will be inserted in its place in-game.
• In some cases, a value should not be translated literally. The key and the value should always be taken into account when making any translation.
  • Example: In English, "lang_pause_title" has the value "Paws". This is a pun that only works in English. To translate this value to another language, it is recommended that you translate the word Pause, not the word Paws.
• In some cases, a value will store a piece of special dialog. If so, it may use special markup such as BBCode or line breaks. Please see our section on Dialog Files for more information on how these features work.
• In rare cases, the value of a key will be a pointer to another key. In these cases, the value will begin with lang_ and should not be translated.
  • Example: "lang_example_key": "lang_example_key_2",
• In rare cases, the key will contain the substring "do_not_translate". In these cases, the value should not be translated.
  • Example: "lang_example_key_do_not_translate": "special_value",

Special Keys

The following keys have very specific allowed values. Below is a table of all special keys, their possible values, and a brief description.

Language Icons

Optionally, each localization language can have its own Language Icon, a small pixel art representation of the language (typically an associated country flag.) It is very simple to add a language icon to an existing language, simply add a 32x32 resolution .png file to the /gameresources/languages/sprites directory and name it {LanguageUID}.png (for example, english.png.)

Time

Time passes in Cattails: Wildwood Story at a constant rate. This rate is represented by the time_tick value, which can be modified in the time.meta file. This file is located in the /gameresources/time directory.

By changing the value of time_tick, you can effectively make the days pass quicker or slower, depending on your preference. A lower value will make time pass faster; a higher value will make time pass slower. By default, time_tick has a value of 40.

time_tick has a minimum value of 1 and a maximum value of 200.

NPCs

The world of Cattails: Wildwood Story is inhabited by many NPCs (Non-Player Characters), with a broad range of personalities, schedules, and types.

NPC data is found within the Game Installation Path (see discussion above) under the /gameresources/npcs directory.

Portraits

The simplest NPC modification involves changing the NPC's portrait appearance. These portraits are displayed to the player when speaking with the appropriate NPC. NPC portraits are stored as PNG image files in the /gameresources/npcs/portraits directory. Below are a few examples of NPC portrait files:

Each portrait file showcases one of 8 emotions (neutral, playful, happy, sad, angry, thinking, shocked, angry, blushing) or 1 unique portrait that is reserved for each character (Special).

A portrait file is a PNG image that is 416x416 resolution. The naming convention is as follows:

1. NPC Unique Identifier (usually their "english" name, which must be identical to the NPCs .meta file name [see below]);
2. Emotion (neutral/playful/happy/sad/angry/thinking/shocked/angry/blushing/special);
3. Terminated by the file extension, .png.

A few examples of NPC portrait file names:

• ellineutral.png
• krampyangry.png
• cocoplayful.png
• buttercupsad.png
• emberspecial.png

In most cases, the special portrait is an identical copy of the neutral portrait, but it has been provided to add some flexibility to particularly creative users.

You can use Portrait PNGs to replace existing characters' in-game portrait appearances, or add portraits to new custom-made NPCs.

Icons

Each NPC has a face icon, which will be displayed on the minimap and may appear in various GUIs like dialog and the social panel. If an NPC is not provided an Icon, their icon will appear as a black silhouette of a cat with a "?" on it.

Icon files are stored in the /npcs/icons directory. They must be .png files, 64x64 resolution. They should be named #NPC_UID#icon.png. For example, charlotteicon.png or molbyicon.png.

Metadata

Each NPC has a .meta file which contains appearance data, scheduling data, and other relevant info about the character.

The naming convention for Metadata files is as follows:

1. NPC Unique Identifier (usually their "english" name);
2. Terminated by the file extension, .meta

A few examples of NPC Metadata file names:

• elli.meta
• krampy.meta
• coco.meta
• buttercup.meta

The contents of a .meta file are structured in the JSON format. Essentially, the contents are structured as human-readable key-value pairs. Below is a sample from Coco.meta:

Below is a table listing all NPC Metadata keys and their possible values.

Buddy System Traits

Many NPCs can be brought along for an adventure once the player reaches a high enough level of friendship. This is called the buddy system. Each NPC can optionally have a Passive Trait and an Active Trait that augment their abilities while participating in the buddy system. Below is a full list of all possible traits an NPC can possess:

• Vivacious: This NPC has increased maximum health.
• Tough: This NPC has increased attack damage.
• Lucky: This NPC is considered lucky, increasing the Luck stat while adventuring with the player.
• Hardy: This NPC is immune to all negative status effects, including poison.
• Adaptive: This NPC will earn Buddy XP faster.
• Inspiring: This NPC inspires all nearby fighters from your colony to deal bonus damage.
• Subtle: This NPC has an easier time catching prey and makes it easier for the player to catch prey, too.

• Enterprising: This NPC will occasionally find hidden Mews while adventuring.
• Renowned: This NPC gains a small amount of influence for your colony in the current region over time.
• Caring: This NPC may heal a small amount of the player's health when it gets low.
• Persistent: This NPC may randomly break all nearby rocks while mining.
• Delicate: When this NPC picks a growing herb, there is a random chance they will harvest a variety that is 1 rank better than what was growing.
• Fierce: This NPC may randomly apply a damage-over-time effect to all nearby enemies.
• Keen: When hunting prey, this NPC has a random chance of catching 2 prey instead of 1.

Scheduling

Some NPCs have schedules, daily timestamps that specify where that NPC should exist in the world and what their behavior should be once they get there. Some NPCs do not have schedules and will always exist at a set place with a set behavior.

NPCs schedules are specified in the optional "npc_schedule" key of the NPC's .meta file. NPCs that do not have a schedule do not have a "npc_schedule" key in their respective .meta file.

NPCs will attempt to logically path between their schedule points at the appropriate times; but note that if an NPC is unable to path to their given schedule point, they may fall back to certain default behaviors (like standing outside their own den instead of a non-existent building) or even instantaneously teleport if necessary. It is important that any two chronologically-adjacent schedule blocks be in adjoining map regions so that the NPC can find an intuitive and logical path between the map regions. Otherwise, they will most definitely teleport instead of pathing more than 1 map region away.

"npc_schedule" contains a list of Schedule Block JSON objects. Each Schedule Block JSON object specifies a place where the NPC should be located and may optionally specify a schedule block type, a region, a time, a behavior for the NPC to exhibit, etc.

Ranks

Every NPC that is befriendable:true has a friendship rank with the player that can change over the course of play.

Additionally, every NPC that is datable:true has dating and marriage ranks with the player.

Each category of ranks has a value between 0-4. Typically, the player begins at rank 1 friendship at the start of the game with each of these NPCs. If they begin dating an NPC, they usually enter the dating relationship at rank 1 dating. If they marry, they usually enter the marriage relationship at rank 1 marriage.

Friendship is noted with star icons near the NPC's portrait.

Dating is noted with heart icons near the NPC's portrait.

Marriage is noted with ring icons near the NPC's portrait.

Here's an important note: If you are dating OR married to an NPC, you are ALSO considered to be rank 4 friendship with that NPC. However, if you are married to an NPC, you are NOT considered to be dating that NPC.

It is possible for an NPC that is dating or married to the player to be so miserable in the relationship that they want to break up with the player. This will automatically happen if the player is at rank 0 dating or marriage with that NPC and continues to treat them poorly, by either ignoring them or giving them bad gifts repeatedly.

Dialog Files

Each NPC has multiple Dialog Files, which store translated versions of the NPC's name and dialog. These files may be modified to change dialog or introduce new dialog lines into the game. Additional Dialog Files may be created to add support for additional languages.

Dialog files are located in the /gameresources/npcs/lang directory of the Game Installation Path (see above discussion.) For each NPC, there will be 1 Dialog File for each language.

The contents of a Dialog File are structured in the JSON format. Essentially, the contents are structured as human-readable key-value pairs.

The naming convention for Dialog Files is as follows:

1. NPC Unique Identifier (typically, their "english" name);
2. Terminated by the file extension, .lang

A few examples of Dialog File names:

• elli.lang
• krampy.lang
• coco.lang
• buttercup.lang

These files contain several important pieces of translatable text associated with a given NPC. For example, the NPC's display name may be translated within these files. Below is a table listing of important keys, along with descriptions of what they should hold:

Dialog may contain special markup strings and commands that give it a unique appearance or animation. Below is a table of all possible commands and special strings:

Please note that these special effects are only available within Dialog strings.

Question & Answer Prompts

Occasionally, an NPC will have a question for the player, or a branch in their dialog. The game can display multiple answer options for the player to choose from, and the dialog will progress based on the player's answer.

For a simple example, consider an NPC who wants to ask the player a question about their opinion on the taste of Snake. Here's what this interaction looks like within a Dialog File:

"lang_npc_neutral_dialog_0": "[neutral]Hello, #player_name#. I had a question for you... what do you think about the taste of [green]Snake[/green]?",
"lang_npc_neutral_dialog_0_choice_0": "It's delicious!",
"lang_npc_neutral_dialog_0_choice_0_path": "lang_npc_snake_is_delicious",
"lang_npc_neutral_dialog_0_choice_1": "It's disgusting!",
"lang_npc_neutral_dialog_0_choice_1_path": "lang_npc_snake_is_disgusting",
"lang_npc_neutral_dialog_0_choice_2": "I have no opinion.",
"lang_npc_neutral_dialog_0_choice_2_path": "lang_npc_snake_no_opinion",

"lang_npc_snake_is_delicious": "[happy]Oh, really? I thought I was the only one who loved the taste of [green]Snake[/green]! Glad to know I'm not alone.",
"lang_npc_snake_is_disgusting": "[shocked]Wow, you have a very strong opinion on this subject. [sad]I'll bet you've never even tried it.",
"lang_npc_snake_no_opinion": "[thinking]Next time I catch one, I'll be sure to share with you. [happy]Then we can figure it out together!",


There's a lot to break down in the above example, so let's walk through each part:

First, you have the dialog that precedes the question. In this example, that's the value of "lang_npc_neutral_dialog_0".

Then, we've appended several choices to that dialog prompt by adding a few keys directly below it. In this example, our choices are "lang_npc_neutral_dialog_0_choice_0", "lang_npc_neutral_dialog_0_choice_1", and "lang_npc_neutral_dialog_0_choice_2". You can append up to 10 choices (0-9) to any given dialog prompt.

Next, we've added choice paths, which tell the dialog what "path" to take when the player selects the associated choice. In this example, our choice paths are "lang_npc_neutral_dialog_0_choice_0_path", "lang_npc_neutral_dialog_0_choice_1_path", and "lang_npc_neutral_dialog_0_choice_2_path". The values of these choice paths must be another dialog prompt's key.

Finally, we've implemeted the dialog that will display for each possible player choice. In the above example, these are "lang_npc_snake_is_delicious", "lang_npc_snake_is_disgusting", and "lang_npc_snake_no_opinion".

This is a powerful tool that can be added to any dialog prompt to add depth and flavor to an NPC. In general terms, you can add a question & answer prompt in the following manner:

1. Locate a dialog prompt that you wish to add a question & answer prompt to.
2. Copy the key of the dialog prompt (for example, "lang_example".)
3. Create new keys below the dialog prompt. Name them the same as the dialog prompt, plus the string "_choice_#" (where # is an integer between 0-9). (For example, "lang_example_choice_0".) Give them values that will appear to the player in-game.
4. For each "choice" key created in the previous step, create one new key. Name these the same as the choice key, plus the string "_path". (For example, "lang_example_choice_0_path".) Give them values that point to new dialog keys.
5. For each "choice_path", create the associated new dialog key. Fill in these values with dialog that will appear to the player when the associated choice is selected.

Dialog Objects

When the player talks to an NPC, the NPC can reply with a variety of dialog possibilities. Often these bits of dialog center on thoughts or opinions about the current situation in-game. For example, a character may make a remark about the weather, or about their relationship with the player. All of these dialog possibilities are stored in Dialog Objects, which are contained in the "dialog" array within the NPC's Meta file.

At the start of each day, an NPC will select 1 dialog object to be active. When the player talks to the NPC, the NPC will quickly calculate if it needs to switch to a new dialog object, or if the existing dialog object is satisfactory, in which case it will not change.

These Dialog Objects contain data that determines when each piece of dialog can be displayed. Note that the actual translated text displayed to the player is stored separately in the NPC's lang file, not directly in the dialog objects.

In the Dialog Objects "dialog" array, each Dialog Object contains the following keys:

Special Dialog Language Keys

There are a small handful of special dialog language keys that allow the NPC to perform special behaviors, such as offering a gift to the player. These special keys are noted below. In order to use the effects of one of these keys, set the "dialog_lang_key" of a Dialog Object to the value listed in the table below.

Dialog Object Filters

Use these filters to provide prerequisites that must be met before a particular dialog object will display to the player.

Below is a table of all available filters.

Rival Marriages

Some predetermined pairings of NPCs may eventually end up together, married, and possibly have kittens of their own (unlockable NPCs) as the game progresses. These pairings, along with all their associated data (including which kittens they will have!) are stored in rival marriage .meta files.

Each pairing should have its own .meta file. The name for this file can be decided arbitrarily, but we've gone with {partner_uid}and{partner_uid}.meta for the official ones.

Within these files are stored the following key/value pairs:

Events

Events are special cutscenes that can take place over the course of gameplay. An event interrupts the flow of regular gameplay to introduce a short narrative segment, then wraps up and resets the game to the state it was in prior to the event.

Events are stored in the /gameresources/events directory. These files are named {eventUID}.meta and must be uniquely named.

Below is a table listing all the associated keys an event.meta file can have:

Event Filters

Event filters should be carefully specified as they are essentially requirements that must be satisfied in order for a particular Event to occur.

Below is a table of all valid Event Filters and their associated values:

Event Blocks

Event Blocks allow you to specify a step-by-step listing of things that will occur during this Event. The Event controller will step through each Event Block, one at a time, starting with the topmost block and ending with the bottommost block, executing the commands contained within in their proper order. Once all Event Blocks have been exhausted, the event will automatically end.

Each Event Block is comprised of a JSON Object with a variety of special keys, specific to the type of Event Block. The one key that remains constant across all types of Event Blocks and must be included in each is "block_type" (as this tells the game what type of Event Block object this particular Event Block is.)

Here is an example Event Block JSON object:

Here is a helpful listing of all Event Block types, along with their associated keys.

• "block_type": "wait"
  • "seconds": # (required) Specifies the number of seconds to wait before continuing with the event. Useful for pauses.
• "block_type": "camera"
  • "cat_uid": "{catUID}" (optional) Specifies a particular cat to focus the camera on (i.e. "spark".) You can also set this value to "player" to focus the camera on the player.
  • "x": #, "y": # (optional) Specifies a particular x,y coordinate to center the camera on. Must use both "x" and "y" parameters together in an event block if one is specified.
• "block_type": "warp_player"
  • "x": #, "y": # (required) Warps the player to the specified x,y coordinates immediately.
  • "direction": "north/east/south/west" (required) Specifies which direction the player should be facing after the immediate warp.
• "block_type": "warp_npc"
  • "npc_uid": "{npcUID}" (required) Warps the specified NPC (i.e. "spark") to the specified x,y coordinates immediately.
  • "x": #, "y": # (required) Warps the specified NPC (i.e. "spark") to the specified x,y coordinates immediately.
  • "direction": "north/east/south/west" (required) Specifies which direction the NPC should be facing after the immediate warp.
  • "behavior": "standing/sleeping/sitting" (required) Specifies the behavior the NPC should adopt after the immediate warp. Default is "standing".
• "block_type": "dialog"
  • "speaker_uid": "{npcUID}" (required) Specifies the speaker UID of the NPC who will say this line of dialog. You can also use the special string "narrative" to get a generic grey dialog box instead.
  • "lang_key": "{langKey}" (required) Specifies which specific line of dialog to trigger here, matching a key from a .lang file. For example, "lang_event_dialog_0"
• "block_type": "dialog_branch"
  • "speaker_uid": "{npcUID}" (required) Specifies the speaker UID of the NPC who will say this line of dialog. You can also use the special string "narrative" to get a generic grey dialog box instead.
  • "lang_key": "{langKey}" (required) Specifies which specific line of dialog to trigger here, matching a key from a .lang file. For example, "lang_event_dialog_0"
  • "choice_#_key": "{langKey}" (optional, 1-6) Specifies the first choice text language key, matching a key from a .lang file. For example, "lang_event_choice_1"
  • "choice_#_path": "{newEventBlockUID}" (optional, 1-6, required for each "choice_#_key" present) Specifies which new Event Block list the event should proceed down if the associated choice is picked. For example, "event_blocks_yes_response" or "event_blocks_no_response". The new Event Block list will override the default "event_blocks" list for the remainder of the Event. You must create the new Event Block list yourself and name it the same name as the {newEventBlockUID} specified in this key.
  • "choice_#_consequences": { ... } (optional, 1-6) Specifies a list of mechanical consequences that will occur if the associated choice is selected by the player. A full listing of possible consequences and their values is below:
    • "friendship_change_{npcUID}": # Changes the player's friendship/dating/marriage value with the associated NPC by the amount specified (use negative numbers to lose friendship points.)
• "block_type": "move_npc"
  • "npc_uid": "{npcUID}" (required) Specifies which NPC to move (i.e. "spark".)
  • "x": #, "y": # (required) Specifies the coordinate to move this NPC to.
  • "direction": "north/east/south/west" (required) Specifies which direction this NPC should face once they reach their destination.
  • "behavior": "standing/sleeping/sitting/destroy" (required) Specifies the behavior this NPC should adopt upon arrival at their destination. Default behavior is "standing".
  • "speed_mod": # (optional) Changes this NPC's movement speed for this move command. This is a multiplier; 1.0 means regular speed; 0.5 means half speed; 2.0 means double speed; etc.
• "block_type": "move_player"
  • "x": #, "y": # (required) Specifies the coordinate to move the player to.
  • "direction": "north/east/south/west" (required) Specifies which direction the player should face once they reach their destination.
• "block_type": "spawn_item"
  • "item_uid": "{itemUID}" (required) Specifies which item to spawn (must be a valid Item UID, i.e. "Trout").
  • "x": #, "y": # (required) Specifies the coordinate where the item should spawn.
• "block_type": "emote"
  • "target": "{npcUID}/player" (required) Specifies which cat this emote will appear at (i.e. "krampy" or "player").
  • "emote_type": "meow/heart/check/x/distress/exclam/question/ellipsis" (required) Specifies the type of emote to display on the target cat.
  • *special note: this event type includes a 3-second pause after the emote is spawned to give time for the player to see the emote before moving on.
• "block_type": "hold_item"
  • "target": "{npcUID}/player" (required) Specifies which cat this item will appear to be held by (i.e. "krampy" or "player").
  • "item_uid": "{itemUID}" (required) Specifies the type of item that the target cat will appear to be holding (i.e. "Frog").
• "block_type": "drop_item"
  • "target": "{npcUID}/player" (required) Specifies which cat should drop their currently-held event item (i.e. "lainey" or "player").
• "block_type": "grant_item"
  • "item_uid": "{item_uid}" (required) Specifies which item should be granted to the player (i.e. "Honeycomb" or "Raspberries [Poor]"). Note that only 1 of the item can be granted to the player for each of these event blocks. If the player's inventory is full at the moment the item is granted, it will instead be added to their storage.

Bundles

Bundles allow you to lock access to a particular NPC until a number of specific items have been donated. This is how the "recruiting new cats to your colony" feature operates.

The player can visit the Pillar of the Wildwood in the Temple of the Forest Guardian and view up to 6 active Bundles at a time. By donating the requisite items, a Bundle may be completed, in which case it will disappear from the Pillar of the Wildwood and the associated NPC(s) will be unlocked for the player to interact with from that point onward.

Each Bundle has 1 associated .meta file in the /gameresources/bundles directory. This files may be named anything you like as all the important data is stored inside.

Below is a table listing the important keys and possible values for a Bundle .meta file:

Shops

Several NPCs run shops where the player can purchase items, accessories, and upgrades. The Shop .meta files, located within the Game Installation Path under the /gameresources/npcs/shops directory (see above discussion), contain all shop data.

Note that shopkeepers will provide a 10% discount on all items in their shop if they are befriendable and the player has achieved a 4-star friendship rank with them.

The contents of a shop.meta file are structured in the JSON format. Essentially, the contents are structured as human-readable key-value pairs. Below is a sample of the structure:

A shop meta file must be named "shop____.meta". For example, "shopember.meta" or "shopdev.meta".

Below is a table of important keys and their possible values, along with descriptions of each.

The special key "shop_items" contains an array of all the available items at a particular shop. An item is listed as a JSON object within this array. Below is an example of the "shop_items" structure:

Below is a table explaining how to structure an Item JSON object:

Item Filters

In some cases, a shop will carry different items at different times. The "item_filters" key exists to serve this function.

The "item_filters" key may optionally be left as an empty JSON object, like so:

"item_filters": {}

In this case, the item will always display in the shop for purchase.

It should also be noted that certain items may only be purchased one time (Accessories, Furniture, and Upgrades.) These items will auto-filter out of the shop if they have already been purchased or unlocked by the player. No need to set a filter for this functionality!

Additionally, ranked Upgrade items (such as "Inventory Upgrade I/II/III") have built-in prerequisites that will automatically apply. For example, Upgrade II will not appear until the player has unlocked Upgrade I. In order to have a shop display all possible ranks for an upgrade, you must add each rank separately to the "shop_items" array.

Below is an example of an item that has been filtered to only appear in the shop in Spring or Summer, Year 2 or later:

"item_filters": {
"filter_spring": true,
"filter_summer": true,
"filter_autumn": false,
"filter_winter": false,
"filter_year": 2
}


Below is a table of all available filters.

Items

There are lots and lots of items to collect in Cattails: Wildwood Story! These items are defined in the item .meta files, which are located in the Game Installation Path (see discussion above) in the /gameresources/items directory.

Item names and descriptions are localized. These files are found within the /gameresources/items/lang directory.

Below is a sample of an item .meta file:

Each item has its own item .meta file. An Item .meta file should be named "___item.meta". For example, "ironoreitem.meta" or "paintedbutterflyitem.meta".

Within each file is a JSON object that corresponds to a single item. In each item JSON object, the following keys may be present:

Ranked Items

Some items are "ranked" (Goldenseal, Marigold, etc.) These items are marked with the special keywords [Poor], [Fair], and [Good] in their item unique identifiers. [Poor] items' names will automatically display with ★; [Fair] items' names will automatically display with ★★; and [Good] items' names will automatically display with ★★★.

All Default Item Unique Identifiers

Item Sprites

Item sprites are stored in the /gameresources/items/sprites directory. Each item has 1 associated sprite in this location. These sprites will display when the item is 1. laying on the ground; 2. being held; 3. in inventory; 4. in a shop.

Item sprites should be 32x32 pixels in resolution (except Accessory item sprites, which should be 20x20) and named in the following manner:

1. The item unique identifier, with no spaces or special characters and all lowercase;
2. Terminated by the file extension, .png.

The following are some examples of valid item sprite file names:

• mouse.png
• goldensealfair.png
• marigoldgood.png
• shinytrinket.png
• tiaraaccessory.png
• valerianpoor.png
• goldore.png

Accessories

Accessory info is stored in Accessory .meta files, which are located in the Game Installation Path (see discussion above) under the /gameresources/items/accessories directory.

Below is a sample of an Accessory .meta file:

An accessory .meta file should be named "_____accessory.meta". For example, "bellaccessory.meta" or "beakyaccessory.meta".

Each accessory .meta file is a single JSON object that corresponds to an Accessory. For each Accessory there should be a matching Item .meta file with the same UID string. Below is a table describing each key in an accessory JSON object:

Accessory Sprites

Accessory sprites can be found in the Game Installation Path (see discussion above) under the /gameresources/items/sprites/accessories directory.

Each Accessory should have 4 or 5 sprites in this location, in 48x48 resolution. These sprites must be named in the following manner:

1. The accessory unique identifier, with no spaces or special characters;
2. A direction string;
3. Terminated by the file extension, .png.

Valid direction strings are right, left, up, down, and (optionally) downalt. DownAlt sprites will be shown only if the cat is using the ear type "cat_missing_ears". This is useful for accessories such as collars.

The following are examples of valid accessory sprite names:

• bellaccessoryright.png
• facescaraccessoryleft.png
• spikecollaraccessorydown.png
• spikecollaraccessorydownalt.png
• whiskersaccessoryup.png

Some of the default accessories have built-in special effects. These are noted below:

• Pets: Pet accessories spawn a pet follower. At this time, it is not possible to mod additional pets into the game.
• Whiskers: The "Whiskers Accessory" automatically blends its color to match the cat's muzzle.
• Face Scar: The "Face Scar Accessory" automatically blends its color to match the cat's face.
• Headlamp: The "Headlamp Accessory" automatically casts a beam of light around the player. This accessory also interacts with the Headlamp Upgrades and can illuminate a dark area.

Additionally, it should be noted that the order in which the accessories are listed in the "accessories" array will determine what order the accessories will be drawn in-game. Later entries will draw beneath earlier entries.

Herbs

Herbs are special items that may spawn once per day in each map region randomly. An herb item will despawn if a full day passes and the player leaves the map region in which it spawned.

Herbs always grow on plants. The default herb plant is a small cluster of leaves, like a flower. Alternatively, an herb may grow on a Bush. You can specify which item unique identifiers should grow on a bush instead of a leaf cluster via the bushherbs.meta file, located in the /gameresources/herbs directory.

Herbs may be ranked or unranked. A ranked herb has multiple versions of the same item, noted by 3 different unique identifiers ([Poor], [Fair], and [Good].) Unranked herbs simply have 1 version of the item, and thus 1 unique identifier.

Examples of Ranked herbs:

• Licorice [Poor/Fair/Good]
• Goldenseal [Poor/Fair/Good]
• Thistle [Poor/Fair/Good]
• Catnip [Poor/Fair/Good]
• Foxglove [Poor/Fair/Good]

Examples of Unranked herbs:

• Daisy
• Red Rose
• Black Rose
• Queen of the Night

To specify if an item is a ranked herb, you must add it to the list of ranked herbs within the rankedherbs.meta file, located in the /gameresources/herbs directory. When doing so, only include the part of the item unique identifier of the herb that does not include [Poor], [Fair], or [Good]. (ex. "Raspberries" or "Goldenseal".)

Each herb will only grow in certain seasons. To specify which seasons to allow which herbs to grow, edit the seasonalherbs.meta file, located in the /gameresources/herbs directory. Add the item unique identifiers for each herb to each season that you would like to allow them to grow in. When doing so, only include the part of the item unique identifier of the herb that does not include [Poor], [Fair], or [Good]. (ex. "Raspberries" or "Goldenseal".)

Any item may be treated as an herb and grow randomly throughout the world. But remember, you must add the item unique identifier to the seasonalherbs.meta list for the appropriate seasons, or else it will never spawn!

When spawning herbs, the game will take into account the item's rarity. More common items are more likely to spawn as herbs than rare items.

Some herbs only grow at night (8pm or later.) You can specify which herbs should only be found at night by editing the nightherbs.meta file, located in the /gameresources/herbs directory. It's important to note that night-time herbs are spawned at the same time as all other herbs, but they will not appear to the player until it is night-time. Night herbs do count towards the total number of spawned herbs in a given map region on any given day.

You can change which herbs will spawn in which areas by editing the mapregions.meta file (see below.)

Item Language Files

For a full discussion on Language Files, see above.

Translations for the name & description of each item are stored in the /gameresources/items/lang directory. For each language, there should exist 1 subdirectory with the name of the language. For example, for english, the item .lang files should all be stored in the /gameresources/items/lang/english directory.

Within this directory should be placed 1 .lang file for each item .meta file, named in the same manner. For example, an item meta file named goldensealitem.meta should have 1 matching goldensealitem.lang file for each language in the appropriate /gameresources/items/lang/* directories.

Each item .lang file stores 6 keys, labelled "item_uid_do_not_translate", "lang_item_name", "lang_item_demonstrative_article", "lang_item_definite_article", "lang_item_indefinite_article", and "lang_item_description". Give these key the appropriate values.

Here is an extended example:

Suppose we have an item which has the unique identifier of "Scallop". Let's assume that we must provide translations in english, español, français, and deutsche.

This item has an Item Meta File named scallopitem.meta stored in the /gameresources/items directory.

Now, we must provide the language files. We do this by placing a file named scallopitem.lang in each of the following directories:

• /gameresources/items/lang/english
• /gameresources/items/lang/español
• /gameresources/items/lang/français
• /gameresources/items/lang/deutsche

If the above directories do not exist, we create them before placing the files there.

Then, we open each ScallopItem.lang file and fill it in with the appropriate language translations and UID. For example, we would fill in the english .lang file in the following manner:

Furniture

Furniture can be used to decorate your den. A piece of furniture has many properties that can be modified through the furniture files. These files can be found at the /gameresources/furniture directory.

Each type of furniture has several files associated with it:

• A .meta Metadata file;
• An image file (spritesheet); and
• One or more .lang language files, one per installed language.

Furniture Meta Files

The furniture .meta file contains all the properties and behaviors of the furniture piece. The name of the file should be {FurnitureUID}.meta, where {FurnitureUID} is the furniture piece's unique identifier (must be unique.) For example, grassbed.meta or celestiallamp.meta.

The following table lists all properites of the Furniture .meta file, noting which keys are required and which are optional.

Here's a visual reference for the blocker region (if is_solid, an impassable region; in all cases, the region used for placement/removal of the furniture) of a freestanding furniture item. Note that rotatable items may have 1 blocker region that applies to all 4 directions; or they may have 4 separate blocker regions, one for each unique cardinal direction.

Furniture Language Files

For a full discussion on Language Files, see above.

Translations for the name & description of each piece of furniture are stored in the /gameresources/furniture/lang directory. For each language, there should exist 1 subdirectory with the name of the language. For example, for english, the furniture .lang files should all be stored in the /gameresources/furniture/lang/English directory.

Within this directory should be placed 1 .lang file for each furniture .meta file, named in the same manner. For example, a furniture meta file named grassbed.meta should have 1 matching grassbed.lang file for each language in the appropriate /gameresources/furniture/lang/* directories.

Each furniture .lang file stores 2 keys, labelled "lang_furniture_name" and "lang_furniture_description". Give these key the appropriate values.

Here is an extended example:

Suppose we have a furniture piece which has the unique identifier of "campfire". Let's assume that we must provide translations in english, español, français, and deutsche.

This item has an furniture Meta File named campfire.meta stored in the /gameresources/furniture directory.

Now, we must provide the language files. We do this by placing a file named campfire.lang in each of the following directories:

• /gameresources/furniture/lang/english
• /gameresources/furniture/lang/español
• /gameresources/furniture/lang/français
• /gameresources/furniture/lang/deutsche

If the above directories do not exist, we create them before placing the files there.

Then, we open each campfire.lang file and fill it in with the appropriate language translations. For example, we would fill in the english .lang file in the following manner:

Furniture Image Files

A furniture image file is a .png image that contains one or more separate sprites, separated into cells. A furniture image file may be any size.

If a piece of furniture is neither rotatable nor seasonal, this image file will only contain 1 subimage. This is the most simple case.

If a piece of furniture is only rotatable or seasonal (not both), this image file will contain 4 subimages, which will either be 1. the same item in 4 directions; or 2. the same item in 4 seasonal variants.

or

If a piece of furniture is both rotatable and seasonal, this image file will contain 16 subimages, which the game will automatically separate by dividing the width of the image cleanly into 16 even parts. This is the most complex case.

Below is an example of a furniture image file that is neither rotatable nor seasonal:

Below is an example of a furniture image file that is rotatable, but not seasonal:

Below is an example of a furniture image file that is seasonal, but not rotatable:

Animated Furniture Image Files

Optionally, a furniture piece may have a looping animation, which may be up to 10 frames in length. You can set the speed of the animation by modifying the animation_speed property of the furniture's .meta file.

To animate a furniture piece, you must place multiple image files in the resources/furniture/images folder. Their names must all follow the format: {furnitureName}{frameNumber}.png, where {furnitureName} is the same string across all files of the same furniture piece, and {frameNumber} is an integer ranging from 0 to 9. For example, fireflyjar0.png, fireflyjar1.png, fireflyjar2.png, etc.

Mail

Throughout the course of the game, the player may receive mail in their personal mailbox. Mail might just be a simple letter, or it may contain a gift for the player as an attachment.

A piece of mail will be received by the player as soon as all of its filters are satisfied and a once-a-day new mail check has passed. The once-a-day new mail check occurs immediately when a new day arrives.

Each letter, or piece of mail, is comprised of the following:

• A .meta Metadata file;
• One or more .lang language files, one per installed language.

Mail Meta Files

The mail .meta file contains all the properties and behaviors of the piece of mail. The name of the file should be {MailUID}.meta, where {MailUID} is the piece of mail's unique identifier (must be unique.) For example, newyearletter1.meta or cocogreetingcard.meta.

The following table lists all properites of the Mail .meta file, noting which keys are required and which are optional.

Mail Paper Types

"parchment"

"lined"

"starry"

"fancy"

"dark" (Special property: Text is rendered WHITE against this paper type.)

"pinstripe"

"blueprint" (Special property: Text is rendered WHITE against this paper type.)

"cats"

"plants"

"modern"

"plaid"

"drawing"

Mail Filters

Use these filters to provide prerequisites that must be met before a particular piece of mail will be sent to the player.

Below is a table of all available Mail filters.

Mail Language Files

For a full discussion on Language Files, see above.

Translations for the name & description of each piece of mail are stored in the /gameresources/mail/lang directory. For each language, there should exist 1 subdirectory with the name of the language. For example, for english, the mail .lang files should all be stored in the /gameresources/mail/lang/english directory.

Within this directory should be placed 1 .lang file for each Mail .meta file, named in the same manner. For example, a Mail meta file named TestMail1.meta should have 1 matching testmail1.lang file for each language in the appropriate /gameresources/mail/lang/* directories.

Each mail .lang file stores 4 keys, labelled "lang_mail_subject", "lang_mail_content_header", "lang_mail_content_body", and "lang_mail_content_signature". Give these key the appropriate values.

Here is an extended example:

Suppose we have a piece of mail which has the unique identifier of "greetingcard1". Let's assume that we must provide translations in english, español, français, and deutsche.

This mail has a mail meta file named greetingcard1.meta stored in the /gameresources/mail directory.

Now, we must provide the language files. We do this by placing a file named greetingcard1.lang in each of the following directories:

• /gameresources/mail/lang/english
• /gameresources/mail/lang/español
• /gameresources/mail/lang/français
• /gameresources/mail/lang/deutsche

If the above directories do not exist, we create them before placing the files there.

Then, we open each greetingcard1.lang file and fill it in with the appropriate language translations. For example, we would fill in the english .lang file in the following manner:

You can use the special keys #player_name# and #npc_name_{NPC_UID}# to insert any NPC's name (ex. "#npc_name_krampy#") or the player's name into any of these 4 keys.

Map Regions

The Map is composed of several chunks of regional data, referred to as Map Regions. These regions are logically ordered in a 2D grid, each region having its own (x,y) coordinate within the grid. The player may traverse between any two adjacent regions in the grid by moving their character in-game to the boundary between the two regions, assuming they are not blocked by any obstacles.

Here is an example of what a map grid "looks" like, with each region's unique identifier and (x,y) coordinates filled in:

There is some important metadata about the Map stored in the map.meta file, located in the /gameresources/map directory. Below is a table describing all the keys available in the map.meta file:

Map Region info is stored in the map region .region files, located in the Game Installation Path (see discussion above) under the /gameresources/map directory. Each region has its own file.

Each map region .region file should be named uniquely as the file name is used as the map region's unique identifier. Below are a few examples of appropriate map .region file names:

• testregion.region
• forestcentral.region
• crystalcavern.region

A typical map .region file may look like this:

{
"region_data": {
"template": "Empty",
"region_music": "seasonalexteriorpack",
"region_battle_music": "seasonalbattlepack",
"region_coordinate": [50,50],
"pass_time": true,
"interior": false,
"show_mews": true,
"show_mole_cash": false,
"show_festival_tokens": false,
"show_task_tokens": false,
"max_prey": 3,
"max_bugs": 10,
"max_herbs": 8,
"max_mushrooms": 3,
"spawn_ladybugs": true,
"spawn_moths": true,

...

"spawners": [
{
"type": "item",
"item_uids": ["Scallop", "Conch", "Whorl", "Coral", "Turret"],
"x": 126,
"y": 256,
"percent_chance": 25
}
],

"world_objects": [],

"custom_sprites": [],

"water_tiles": [],

"path_tiles": [],

"cliff_tiles": [],

"stair_tiles": [],

"decorative_tiles": [],
...
"herbs_list": [
"Goldenseal",
"Valerian",
"Thistle",
"Foxglove",
"Blueberries"
],

"prey_list": [
"Mouse",
"Shrew",
"Wren",
"Barbel",
"Adder",
"Rat"
]
}
}

Below is a table that will explain in detail each key located within these files.

Background Types

"grass"	"sand"	"dirt"	"rock"
"basalt"	"void"	"swamp_grass"	"temple_brick"	"dark_ruins_brick"

World Map Sprite

There is a decorative World Map that is displayed to the player via the in-game Map menu. This image is named worldmap.png and it is stored in the /gameresources/map directory.

This image is 500x500 resolution. If you change the structure or features of the map regions, you may consider updating this image as well to reflect your changes.

Region Templates

Each map region is built upon a template. Templates are predefined groupings of decorative tiles, water tiles, and world objects such as trees or rocks. They also include predefined herb spawning locations, beehive locations, and some may include general item spawners. The purpose of templates is to make the life of a map designer easier by providing a basis upon which to build a new map region.

In some cases, you may want to start with a blank canvas for a new map region. In this case, you'll want to use the "Empty" template. Below is a listing of all allowed values for a map region template.

Template Image Previews

Empty

World Objects

A map region may be filled with many World Objects. These are typically things like trees, rocks, laterns, etc. World Objects are specified in the "world_objects" key of each map region file.

Below is an example of a World Object:

If the above JSON object is placed within a region's "world_objects" key, then an oak tree will be spawned in that map region at the coordinate (32,64).

When specifying the coordinates of a World Object, note that the origin point of the object is typically near the bottom-middle of its sprite. Exceptions to this rule are noted in the list below.

Below is a table explaining each key of a World Object:

Several World Objects can be modified to change their default look and collision boundaries, with some exceptions. In the table below, any object marked with an asterisk (*) can be placed in a map region, but its default behavior and look cannot be modified at this time.

All Default World Objects

"invisiblewall16x16" * (spawns an invisible wall that will not be visible to the player. The coordinate given marks the middle of the invisible wall.)
"invisiblewall32x32" * (spawns an invisible wall that will not be visible to the player. The coordinate given marks the middle of the invisible wall.)
"invisiblewall32x32_ul" * (spawns a diagonal invisible wall that will not be visible to the player. The coordinate given marks the middle of the invisible wall.)
"invisiblewall32x32_ur" * (spawns a diagonal invisible wall that will not be visible to the player. The coordinate given marks the middle of the invisible wall.)
"invisiblewall32x32_dl" * (spawns a diagonal invisible wall that will not be visible to the player. The coordinate given marks the middle of the invisible wall.)
"invisiblewall32x32_dr" * (spawns a diagonal invisible wall that will not be visible to the player. The coordinate given marks the middle of the invisible wall.)
"destroyer16x16" * (spawns an invisible destroyer object that will destroy any world object, tile, or spawner that touches it. The coordinate given marks the middle of the destroyer. This object is spawned, checks for collisions, destroys colliding objects, then immediately despawns.)
"destroyer128x128" * (spawns an invisible destroyer object that will destroy any world object, tile, or spawner that touches it. The coordinate given marks the middle of the destroyer. This object is spawned, checks for collisions, destroys colliding objects, then immediately despawns.)
"goldmew" * (spawns a floating golden Mew coin, worth 20 Mews.)
"silvermew" * (spawns a floating silver Mew coin, worth 5 Mews.)
"coppermew" * (spawns a floating copper Mew coin, worth 1 Mew.)
"molecash" * (spawns a floating Mole Cash coin, worth 5 Mole Cash.)
"festivaltoken" * (spawns a floating Festival Token, worth 1 Festival Token.)
"tasktoken" * (spawns a floating Task Token, worth 1 Task Token.)
"lamppost" *
"crystallamp" *
"blackcrystallamp" *
"redcrystallamp" *
"traditionallantern" *
"streetlight" *
"mininglantern" * (swings on its chain from an invisible ceiling far above. The origin is the top of the chain, so you'll likely need to spawn it with a y value far lower than you might expect to get the placement right.)
"ancientsconce" *
"bambootorch" *
"celestiallantern" *
"brazier" *
"oaktreea"
"oaktreeb"
"oaktreec"
"oaktreed"
"oaktreee"
"oaktreef"
"oaktreeg"
"oaktreeh"
"oaktreei"
"oaktreej"
"oakstumpa"
"oakstumpb"
"oakstumpc"
"oakstumpd"
"oakstumpe"
"oakstumppowerpaw"
"birchtreea"
"birchtreeb"
"birchtreec"
"birchtreed"
"birchtreee"
"birchtreef"
"birchtreeg"
"birchtreeh"
"birchtreei"
"birchtreej"
"birchstumpa"
"birchstumpb"
"birchstumpc"
"willowtreea"
"willowtreeb"
"willowtreec"
"willowtreed"
"willowtreee"
"willowtreef"
"willowtreeg"
"willowtreeh"
"willowtreei"
"willowtreej"
"willowstumpa"
"willowstumpb"
"willowstumpc"
"willowstumpd"
"willowstumpe"
"pinetreea"
"pinetreeb"
"pinetreec"
"pinetreed"
"pinetreee"
"pinetreef"
"pinetreeg"
"pinetreeh"
"pinetreei"
"pinetreej"
"palmtreea"
"palmtreeb"
"palmtreec"
"palmtreed"
"palmtreee"
"palmtreef"
"palmtreeg"
"palmtreeh"
"palmtreei"
"palmtreej"
"deadtreea"
"deadtreeb"
"deadtreec"
"deadtreed"
"deadtreee"
"deadtreef"
"deadtreeg"
"deadtreeh"
"deadtreei"
"deadtreej"
"gnarledtreea"
"gnarledtreeb"
"gnarledtreec"
"gnarledtreed"
"gnarledtreee"
"pinestumpa"
"pinestumpb"
"pinestumpc"
"pinestumpd"
"pinestumpe"
"busha"
"bushb"
"bushc"
"bushd"
"bushe"
"bushf"
"bushg"
"bushh"
"bushi"
"bushj"
"tropicalbusha"
"tropicalbushb"
"tropicalbushc"
"tropicalbushd"
"tropicalbushe"
"deadbusha"
"deadbushb"
"deadbushc"
"deadbushd"
"deadbushe"
"rocka"
"rockb"
"rockc"
"rockd"
"rocke"
"rockf"
"rockg"
"rockh"
"rocki"
"rockj"
"rockpowerpaw"
"caverocka"
"caverockb"
"caverockc"
"caverockd"
"caverocke"
"caverockf"
"caverockg"
"caverockh"
"caverocki"
"caverockj"
"basaltrocka"
"basaltrockb"
"basaltrockc"
"basaltrockd"
"basaltrocke"
"basaltrockf"
"basaltrockg"
"basaltrockh"
"basaltrocki"
"basaltrockj"
"crystala"
"crystalb"
"crystalc"
"crystald"
"crystale"
"crystalf"
"crystalg"
"crystalh"
"crystali"
"crystalj"
"ruinsa" *
"ruinsb" *
"ruinsc" *
"ruinsd" *
"ruinse" *
"ruinsf" *
"ruinsg" *
"ruinsh" *
"ruinsi" *
"ruinsj" *
"darkpillar" *
"springcarving" *
"summercarving" *
"autumncarving" *
"wintercarving" *
"moleanvil"
"molebellows"
"moletoolrack"
"moletoolbarrel"
"molefurnace" *
"greenthornsa" *
"greenthornsb" *
"greenthornsc" *
"greenthornsd" *
"greenthornse" *
"greenthornsf" *
"greenthornsg" *
"greenthornsh" *
"greenthornsi" *
"greenthornsj" *
"greenthornsk" *
"greenthornsl" *
"greenthornsm" *
"greenthornsn" *
"greenthornso" *
"greenthornsp" *
"greenthornsq" *
"greenthornsr" *
"yellowthornsa" *
"yellowthornsb" *
"yellowthornsc" *
"yellowthornsd" *
"yellowthornse" *
"yellowthornsf" *
"yellowthornsg" *
"yellowthornsh" *
"yellowthornsi" *
"yellowthornsj" *
"yellowthornsk" *
"yellowthornsl" *
"yellowthornsm" *
"yellowthornsn" *
"yellowthornso" *
"purplethornsa" *
"purplethornsb" *
"purplethornsc" *
"purplethornsd" *
"purplethornse" *
"purplethornsf" *
"purplethornsg" *
"signpost"
"stonefencea"
"stonefenceb"
"stonefencec"
"stonefenced"
"abandonedwell"
"stonemarker"

World Object Metadata

Several World Objects can be modified to change their default appearance and collision behavior. It is also possible to create your own custom World Objects.

To do either, you'll need to navigate to the /gameresources/world_objects directory and modify or create new .meta files.

Each World Object has its own .meta file, which will be named #WorldObjectUID#.meta (for example, "oaktreea.meta" or "crystal3.meta".) You can create a new World Object by creating a new .meta file in this location with the appropriate name for your custom World Object's UID.

These files are fairly simple. Let's take a look at the contents of a World Object .meta file:

Below is a table listing each key, along with a short description.

World Object Sprites

Every World Object has 1 or more images (or sprites) associated with it. These sprites are stored in the /gameresources/world_objects/sprites directory.

These sprites must be .PNG image files, but they may be any size (up to a maximum of 2048x2048.) The filename of a sprite stored in this location may be used in a World Object .meta file to bind it to a particular World Object (see above.)

Many World Objects will only have 1 sprite in this directory, but some (such as trees) may have multiple versions so that their appearance will change with the seasons. In general, it's best practice to keep the resolution of all images for a particular World Object at the exact same resolution or else they will become stretched and skewed in-game.

Custom Sprites

Custom sprites are images that will appear to the player in-game, placed at a particular location in the game world. These images can be any arbitrary resolution. Custom sprite image files must be .png files.

A map region may have many custom sprites. There's no limit!

Visually, custom sprites will either appear "below" all world objects (such as trees, rocks, the player, NPCs, etc.) or "above" all world objects. In either case, they will appear above any tiles. When specifying the (x,y) coordinate for any custom sprite, note that the coordinate marks the upper-left hand corner of the image.

Custom sprite files are stored in the /gameresources/custom_sprites directory.

Custom sprite JSON objects should be placed in a map region's "custom_sprites" key. Below is an example of what a Custom Sprite JSON object looks like:

Here's an example. Let's say we have the following image, named smileyface.png, and we want it to appear in the game in a particular game region.

First, we need to add the smileyface.png file to the Cattails: Wildwood Story gameresources folder. We take the image file and place it in the /gameresources/custom_sprites directory.

Then, we need to tell the game where we want to display the custom sprite. So we open up the .region file where we would like to place the image. We edit the "custom_sprites" array like so:

We save the region file and boot up the game. Now, when we move to the appropriate map region and go to the specified coordinates, our beautiful custom sprite appears!

Tile Coordinates

Tiles consist of four general categories: Water Tiles, Cliff Tiles, Stair Tiles, and Decorative Tiles. Tiles can be used to add life to a map region by increasing visual variety.

The most important thing to note about Tiles is that they must be snapped to a 32x32 pixel grid in their placement within the map region. Since every map region is 1440x1440 pixels in size, that means that there are 45x45 possible tile locations (2025 total.)

For example, a Tile placed at tile coordinate [2,3] will appear in the map region at x: 64, y: 96.

Water Tiles

Water Tiles can be used to create bodies of water in a map region (such as rivers, lakes, or oceans.) The player can swim through water tiles, though they can be dangerous if the player lingers too long!

Water Tiles are designed to automatically smooth out their edges for a nice, rounded look, unlike other tiles.

Here is a sample Water Tile:

Like all tiles, they must be snapped to a 32x32 pixel grid, and they use tile coordinates instead of regular coordinates.

Below is a table listing the important information about water tiles:

All Water Tile Types

"none"	Removes an existing water tile from a specified coordinate.
"shallow"	Relatively shallow water, but still too deep to touch the bottom. Cheery light-blue appearance. Freezes in Winter.
"swamp"	Dark, murky water. Freezes in Winter.
"deep"	Relatively deep water, with a deep, regal blue hue. Does not freeze in Winter.
"peculiar"	Strange water with a dark purpleish hue. Glows with faint light. Freezes in Winter.
"mountain"	Very calm shallow water from a serene mountain pool. Freezes in Winter.
"lava"	Red-hot lava. Freezes in Winter.

Decorative Tiles

Decorative Tiles are purely cosmetic. They do not (and cannot) interact with the player or game systems in any way. Still, they are useful in making a region look visually appealing.

Like all tiles, they must be snapped to a 32x32 pixel grid, and they use tile coordinates instead of regular coordinates.

Please also note that Decorative Tiles are not drawn in the player's custom colony map region if the background type is not "grass" or "swamp_grass". In this case, they are automatically made invisible.

Decorative Tiles are stored in tilesets, which are large images composed of many individual 32x32 tiles, oriented in a grid. Each possible tile has 4 variants (spring, summer, autumn, and winter) and there are therefore 4 tileset images total.

To remove an existing Decorative Tile from a map template, place a new Decorative Tile at the same position with a "tile_index" of 0. This will override the existing tile.

Decorative Tiles (Spring appearance)

Each tileset is 512x768 resolution, divided into 32x32 chunks.

To select which tile you'd like to place, you'll need the tile's index. The index is a value from 0-255 that represents its placement within the tileset. 0 is the top-left corner. 1 is the second tile in the top row. 255 is the bottom-right most corner. See below for some examples.

Decorative Tiles are included in a map region's .region file under the "decorative_tiles" key. A typical decorative tile JSON object looks like this:

Below is a table listing the important information about decorative tiles:

Path Tiles

Path Tiles can be used to create pathways through a region. If a Path Tile is placed ontop of a water tile, it will automatically become a bridge.

Path Tiles are designed to automatically smooth out their edges for a nice, rounded look, unlike other tiles.

Here is a sample Path Tile:

Like all tiles, they must be snapped to a 32x32 pixel grid, and they use tile coordinates instead of regular coordinates.

Below is a table listing the important information about path tiles:

All Path Tile Types

"none"	Removes an existing path tile from a region.
"dirt"	A patchwork of hard and soft dirt.
"gravel"	Small pebbles.
"brick"	A horizontally-oriented brick pattern.
"brick_decorative"	A fancy brick pattern.
"concrete"	Paver stones made of solid grey concrete.
"sand"	Grainy sand from a beach.
"white_stones"	Small white stones.
"basalt"	Dark stone with streaks of lava peaking through.
"wood_vertical"	Cut and treated wood planks oriented vertically.
"wood_horizontal"	Cut and treated wood planks oriented horizontally.
"glass"	Glass panes, reinforced with steel borders.
"ice"	Frozen ice. The player can travel faster over this path and even slip out of control.
"dirt_brown"	Dark brown dirt from a deep quarry.
"celestial"	A spectrum of brilliant, translucent colors.
"ruins"	Worn stones, cracked and weathered with age.
"grass"	Looks nearly identical to the normal grass pattern, but with an edge around the borders. Useful to place ontop of other background types (like sand or basalt.)

Cliff Tiles

A map region may contain cliffs to change the elevation of the landscape. These cliffs are stored in a tile grid. Cliffs are placed using tile coordinates.

Use the following method to add cliffs to any map region.

Cliff values must be selected from the following tileset, where the top-left cell is 0, the next tile to its right is 1, etc. Set "type": 0 to delete an existing cliff tile.

Here is a sample Cliff Tile:

Stair Tiles

A map region may contain stairs that the player can walk up and down. These stairs are stored in a tile grid. Stairs are placed using tile coordinates.

Use the following method to add stairs to any map region.

Stair tiles come in 4 types: left, right, up, and down. See the table below.

Stair Tile Type	Image
0
1
2
3

Here is a sample Stair Tile:

All Prey

Spawners

A Spawner is an invisible point in a Map Region that has a chance to spawn something once every day. Spawner definitions should be placed within a map .region file.

There are several types of Spawners:

• item
• herb
• beehive
• grass_(grasses | plains | river | beach | highland | heather | woods | flowers | all) [see below]

Item Spawners

An item spawner can spawn 1 item from a list of items at its location once per day. Any arbitrary item(s) may be spawned via an Item Spawner.

Item Spawners automatically take into account the rarity of the items in their list. Rarer items are less likely to spawn at an item spawner; more common items are more likely to spawn at an item spawner.

If an item spawned by an item spawner is not picked up the same day, it will automatically disappear when the player leaves the map region.

Here is an example of an Item Spawner:

Herb Spawners

An herb spawner can spawn 1 herb from the "herbs_list" defined in the map's .region file at its location once per day. You'll likely want to fill a map region with many of these, as they act as "nodes" where herbs can potentially spawn. Herb spawners obey the maxmium herb number specified in the map's .region file.

If an herb spawned by an herb spawner is not picked up the same day, it will automatically disappear when the player leaves the map region.

Additionally, during Autumn, herb spawners are used as spawning locations for mushrooms. If you do not want mushrooms to appear in a given map region, set the max_mushrooms key to 0 in its .region file.

Here is an example of an Herb Spawner:

Beehive Spawners

A beehive spawner can spawn 1 beehive at its location once per day. Each beehive spawner has a 0.5% chance to spawn a beehive on any given day. Beehives will not spawn in Winter. Additionally, only 1 beehive will spawn per Map Region per day.

Because each beehive spawner rolls its random daily chance separately, adding more beehive spawners means a higher chance of spawning a beehive. You may also consider adding multiple beehive spawners in the exact same location to make that particular location more likely to spawn a beehive.

A beehive spawned by a beehive spawner will disappear when the day is over and the player leaves the area.

Here is an example of a Beehive Spawner:

Grass Spawners

A grass spawner is an invisible point that will spawn 1 cluster of tall grasses at its location once per day. These tall grasses can be destroyed by swiping at them, and occasionally hide small amounts of Mews for the player to find.

Grasses spawned by a grass spawner will disappear when the day is over and the player leaves the area.

There are several types of grass spawners! Each provides a different category of grasses. A table below illustrates all the types of grass spawners and what their grasses look like.

Here is an example of a Grass Spawner:

"grass_grasses"	Pure green grasses, ranging from very short to very tall.
"grass_plains"	Grasses, seeded grass, thorns, and wildflowers.
"grass_river"	Cattails accent the short grasses and wildflowers in this grouping.
"grass_beach"	Short, stubby grasses, along with red heather, tall yellow grass, thorns, and wildflowers.
"grass_highland"	A collection of medium to long grasses, accented by gorgeous blue heather and wildflowers.
"grass_heather"	Short grass and all types of heather.
"grass_woods"	Short grasses, tall grasses, purple heather, yellow grass, seeds, and thorns.
"grass_flowers"	Just short grasses, wildflowers, and seeds.
"grass_all"	All 12 types of grasses can be found in this grouping.

Spawner JSON Objects

Each spawner exists as a JSON object in the "spawners" key of a given Map Region's JSON object. Spawners have the following important keys:

Warps

A warp is an invisible 32x32 zone. If the player collides with a warp zone, they will transition to a new map region. A warp could be used to transition between an interior and exterior location, for example, or for fast travel.

A warp is comprised of the following keys:

Region Language Files

For a full discussion on Language Files, see above.

Translations for the name of each map region are stored in the /gameresources/map/lang directory. For each language, there should exist 1 subdirectory with the name of the language. For example, for English, the region .lang files should all be stored in the /gameresources/map/lang/English directory.

Within this directory should be placed 1 .lang file for each .region file, named in the same manner. For example, a region file named testregion.region should have 1 matching testregion.lang file for each language in the appropriate /gameresources/map/lang/* directories.

Each region .lang file stores a single key, labelled "lang_region_name". Give this key the value of the region's name that should display to the user for the given language.

Here is an extended example:

Suppose we have a region which has the unique identifier of "forestregion". Let's assume that we must provide translations in english, español, français, and deutsche.

This region has a Region File named forestregion.region stored in the /gameresources/map directory.

Now, we must provide the language files. We do this by placing a file named ForestRegion.lang in each of the following directories:

• /gameresources/map/lang/english
• /gameresources/map/lang/español
• /gameresources/map/lang/français
• /gameresources/map/lang/deutsche

If the above directories do not exist, we create them before placing the files there.

Then, we open each forestregion.lang file and fill it in with the appropriate language translation. For example, in the english .lang file, we fill in "lang_region_name": "Forest Region".

Music

As the player wanders the world of Cattails: Wildwood Story, they will hear a variety of background music tracks. You can add music files, override default music files, and change which tracks play at what time.

A music track is must be an .ogg file in order for the game engine to recognize it. The name of the .ogg file is its unique identifier (UID) for all purposes. For example, a file named test.ogg has a UID of "test".

Several .ogg music files come bundled with the game by default and their unique identifiers (UIDs) can be referenced at any time. This is a full list of default music track UIDs:

• none (*A special UID that indicates that NO music track should play)
• maintheme
• titlescreen
• charactercreation
• thetalebegins
• thetalebeginsa
• thetalebeginsb
• thetalebeginsc
• thetalebeginsd
• spring1
• spring2
• spring3
• summer1
• summer2
• summer3
• autumn1
• autumn2
• autumn3
• winter1
• winter2
• winter3
• battlespring
• battlesummer
• battleautumn
• battlewinter
• cozydenspring
• cozydensummer
• cozydenautumn
• cozydenwinter
• festivalspring
• festivalsummer
• festivalautumn
• festivalwinter
• themysteriouswildwood
• thedarkwildwood
• minigametheme
• lovetheme
• romanticrefrain
• suspiciousbehavior
• undergroundindustry
• miningtheme1
• miningtheme2
• miningtheme3
• miningtheme4
• themeoftheforestguardian
• thedarkruins
• patience
• anger
• wrath
• wildwoodrestored
• creditstheme

You can also import your own, custom music tracks by placing their .ogg files in the gameresources/music directory. You can also override the default tracks by placing an .ogg file in this location with the appropriate filename (for example, placing a new track named spring3.ogg in the gameresources/music directory will replace the game's default Spring 3 track with your new version.)

Generally, music plays according to a hierarchy of priority levels. These are the most common priority conditions in the descending order (higher entries mean higher priority:)

1. Event/Cutscene Music
2. Festival Music
3. Battle Music
4. Region Music

Music UIDs are specified in other files. For example, Region Music selections are specified in the appropriate {Map}.region files (see above for more information.)

A Music UID selection can be made in one of two ways: 1) by typing the exact name of a music track UID, in which case the selected track will loop endlessly while its condition to play is met and not overridden by a higher priority selection; or 2) by typing the UID of a Music Pack, which can have additional complex behavior. See below for more information about Music Packs.

Music Packs

If you need additional complexity to determine how music tracks should play in-game, you should use a Music Pack. A Music Pack is a JSON .meta file that can specify several music track UIDs and play them according to a set of conditional rules. For example, a "seasonal" Music Pack can play different tracks depending on the current season, weather, and time of day conditions.

A music pack is named {PackUID}.meta, such as "seasonalexteriorpack.meta" or "deninterior.meta". Music Pack JSON files are simple and contain only a small handful of key/value pairs. Most importantly, the "pack_type" key, which dictates the structure of the rest of the file and which keys should be present. Below is a listing of every valid "pack_type" key and what additional keys should be specified when using each type.

"pack_type": "seasonal"

This pack type exhibits seasonal external behavior. Tracks specified in this type of music pack will play if and only if: 1) it is daytime hours (5am-10pm); and 2) there is no current rain weather event (rain, storms). The active track is selected based on the current season and day.

Additional required keys for this pack type:

• "music_spring_1_3": "{MusicUID}" (Which track to play during Spring 1-3?)
• "music_spring_4_7": "{MusicUID}" (Which track to play during Spring 4-7?)
• "music_spring_8_10": "{MusicUID}" (Which track to play during Spring 8-10?)
• "music_summer_1_3": "{MusicUID}" (Which track to play during Summer 1-3?)
• "music_summer_4_7": "{MusicUID}" (Which track to play during Summer 4-7?)
• "music_summer_8_10": "{MusicUID}" (Which track to play during Summer 8-10?)
• "music_autumn_1_3": "{MusicUID}" (Which track to play during Autumn 1-3?)
• "music_autumn_4_7": "{MusicUID}" (Which track to play during Autumn 4-7?)
• "music_autumn_8_10": "{MusicUID}" (Which track to play during Autumn 8-10?)
• "music_winter_1_3": "{MusicUID}" (Which track to play during Winter 1-3?)
• "music_winter_4_7": "{MusicUID}" (Which track to play during Winter 4-7?)
• "music_winter_8_10": "{MusicUID}" (Which track to play during Winter 8-10?)

"pack_type": "seasonal_interior"

This pack type exhibits seasonal internal behavior. Tracks specified in this type of music pack will play based on the current season, with no time/day conditions. However, during Thunderstorms and Blizzards no track will play in this pack.

Additional required keys for this pack type:

• "music_spring": "{MusicUID}" (Which track to play during Spring?)
• "music_summer": "{MusicUID}" (Which track to play during Summer?)
• "music_autumn": "{MusicUID}" (Which track to play during Autumn?)
• "music_winter": "{MusicUID}" (Which track to play during Winter?)